<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Penlight Documentation</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>Penlight</h1>

<ul>
  <li><a href="../index.html">Index</a></li>
</ul>

<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>


<h2>Modules</h2>
<ul>
  <li><a href="../modules/pl.html">pl</a></li>
  <li><a href="../modules/pl.Date.html">pl.Date</a></li>
  <li><a href="../modules/pl.List.html">pl.List</a></li>
  <li><a href="../modules/pl.Map.html">pl.Map</a></li>
  <li><a href="../modules/pl.MultiMap.html">pl.MultiMap</a></li>
  <li><a href="../modules/pl.OrderedMap.html">pl.OrderedMap</a></li>
  <li><a href="../modules/pl.Set.html">pl.Set</a></li>
  <li><a href="../modules/pl.app.html">pl.app</a></li>
  <li><a href="../modules/pl.array2d.html">pl.array2d</a></li>
  <li><a href="../modules/pl.class.html">pl.class</a></li>
  <li><a href="../modules/pl.comprehension.html">pl.comprehension</a></li>
  <li><a href="../modules/pl.config.html">pl.config</a></li>
  <li><a href="../modules/pl.data.html">pl.data</a></li>
  <li><a href="../modules/pl.dir.html">pl.dir</a></li>
  <li><a href="../modules/pl.file.html">pl.file</a></li>
  <li><a href="../modules/pl.func.html">pl.func</a></li>
  <li><a href="../modules/pl.input.html">pl.input</a></li>
  <li><a href="../modules/pl.lapp.html">pl.lapp</a></li>
  <li><a href="../modules/pl.lexer.html">pl.lexer</a></li>
  <li><a href="../modules/pl.luabalanced.html">pl.luabalanced</a></li>
  <li><a href="../modules/pl.operator.html">pl.operator</a></li>
  <li><a href="../modules/pl.path.html">pl.path</a></li>
  <li><a href="../modules/pl.permute.html">pl.permute</a></li>
  <li><a href="../modules/pl.pretty.html">pl.pretty</a></li>
  <li><a href="../modules/pl.seq.html">pl.seq</a></li>
  <li><strong>pl.sip</strong></li>
  <li><a href="../modules/pl.strict.html">pl.strict</a></li>
  <li><a href="../modules/pl.stringio.html">pl.stringio</a></li>
  <li><a href="../modules/pl.stringx.html">pl.stringx</a></li>
  <li><a href="../modules/pl.tablex.html">pl.tablex</a></li>
  <li><a href="../modules/pl.template.html">pl.template</a></li>
  <li><a href="../modules/pl.test.html">pl.test</a></li>
  <li><a href="../modules/pl.text.html">pl.text</a></li>
  <li><a href="../modules/pl.utils.html">pl.utils</a></li>
  <li><a href="../modules/pl.xml.html">pl.xml</a></li>
</ul>
<h2>Topics</h2>
<ul>
  <li><a href="../topics/01-introduction.md.html">01-introduction.md</a></li>
  <li><a href="../topics/02-arrays.md.html">02-arrays.md</a></li>
  <li><a href="../topics/03-strings.md.html">03-strings.md</a></li>
  <li><a href="../topics/04-paths.md.html">04-paths.md</a></li>
  <li><a href="../topics/05-dates.md.html">05-dates.md</a></li>
  <li><a href="../topics/06-data.md.html">06-data.md</a></li>
  <li><a href="../topics/07-functional.md.html">07-functional.md</a></li>
  <li><a href="../topics/08-additional.md.html">08-additional.md</a></li>
  <li><a href="../topics/09-discussion.md.html">09-discussion.md</a></li>
</ul>
<h2>Examples</h2>
<ul>
  <li><a href="../examples/seesubst.lua.html">seesubst.lua</a></li>
  <li><a href="../examples/sipscan.lua.html">sipscan.lua</a></li>
  <li><a href="../examples/symbols.lua.html">symbols.lua</a></li>
  <li><a href="../examples/test-cmp.lua.html">test-cmp.lua</a></li>
  <li><a href="../examples/test-data.lua.html">test-data.lua</a></li>
  <li><a href="../examples/test-listcallbacks.lua.html">test-listcallbacks.lua</a></li>
  <li><a href="../examples/test-pretty.lua.html">test-pretty.lua</a></li>
  <li><a href="../examples/test-symbols.lua.html">test-symbols.lua</a></li>
  <li><a href="../examples/testapp.lua.html">testapp.lua</a></li>
  <li><a href="../examples/testclone.lua.html">testclone.lua</a></li>
  <li><a href="../examples/testconfig.lua.html">testconfig.lua</a></li>
  <li><a href="../examples/testglobal.lua.html">testglobal.lua</a></li>
  <li><a href="../examples/testinputfields.lua.html">testinputfields.lua</a></li>
  <li><a href="../examples/testinputfields2.lua.html">testinputfields2.lua</a></li>
  <li><a href="../examples/testxml.lua.html">testxml.lua</a></li>
  <li><a href="../examples/which.lua.html">which.lua</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>pl.sip</code></h1>

<p>Simple Input Patterns (SIP).</p>
<p> SIP patterns start with &lsquo;$&rsquo;, then a
 one-letter type, and then an optional variable in curly braces.</p>

<pre><code>sip.match('$v=$q','name="dolly"',res)
==&gt; res=={'name','dolly'}
sip.match('($q{first},$q{second})','("john","smith")',res)
==&gt; res=={second='smith',first='john'}
</code></pre>

<p> &lsquo;'Type names&rsquo;'</p>

<pre><code>v    identifier
i     integer
f     floating-point
q    quoted string
([{&lt;  match up to closing bracket
</code></pre>

<p> See <a href="../topics/08-additional.md.html#Simple_Input_Patterns">the Guide</a></p>

<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#create_pattern">create_pattern&nbsp;(spec, options)</a></td>
	<td class="summary">convert a SIP pattern into the equivalent Lua string pattern.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#compile">compile&nbsp;(spec, options)</a></td>
	<td class="summary">convert a SIP pattern into a matching function.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#match">match&nbsp;(spec, line, res, options)</a></td>
	<td class="summary">match a SIP pattern against a string.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#match_at_start">match_at_start&nbsp;(spec, line, res)</a></td>
	<td class="summary">match a SIP pattern against the start of a string.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#fields">fields&nbsp;(spec, f)</a></td>
	<td class="summary">given a pattern and a file object, return an iterator over the results</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#pattern">pattern&nbsp;(spec, fun)</a></td>
	<td class="summary">register a match which will be used in the read function.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#read">read&nbsp;(f)</a></td>
	<td class="summary">enter a loop which applies all registered matches to the input file.</td>
	</tr>
</table>

<br/>
<br/>


    <h2><a name="Functions"></a>Functions</h2>
    
    <dl class="function">
    <dt>
    <a name = "create_pattern"></a>
    <strong>create_pattern&nbsp;(spec, options)</strong>
    </dt>
    <dd>
    convert a SIP pattern into the equivalent Lua string pattern. 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>options</em></code>:  a table; only the <code>at_start</code> field is
 currently meaningful and esures that the pattern is anchored
 at the start of the string.</li>
    </ul>


    <h3>Returns:</h3>
    <ol>
        a Lua string pattern.
    </ol>


</dd>
    <dt>
    <a name = "compile"></a>
    <strong>compile&nbsp;(spec, options)</strong>
    </dt>
    <dd>
    convert a SIP pattern into a matching function. 
 The returned function takes two arguments, the line and an empty table.
 If the line matched the pattern, then this function return true
 and the table is filled with field-value pairs.

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>options</em></code>:  optional table; {anywhere=true} will stop pattern anchoring at start</li>
    </ul>


    <h3>Returns:</h3>
    <ol>
        a function if successful, or nil,<error>
    </ol>


</dd>
    <dt>
    <a name = "match"></a>
    <strong>match&nbsp;(spec, line, res, options)</strong>
    </dt>
    <dd>
    match a SIP pattern against a string. 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>line</em></code>:  a string</li>
       <li><code><em>res</em></code>:  a table to receive values</li>
       <li><code><em>options</em></code>:  (optional) option table</li>
    </ul>


    <h3>Returns:</h3>
    <ol>
        true or false
    </ol>


</dd>
    <dt>
    <a name = "match_at_start"></a>
    <strong>match_at_start&nbsp;(spec, line, res)</strong>
    </dt>
    <dd>
    match a SIP pattern against the start of a string. 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>line</em></code>:  a string</li>
       <li><code><em>res</em></code>:  a table to receive values</li>
    </ul>


    <h3>Returns:</h3>
    <ol>
        true or false
    </ol>


</dd>
    <dt>
    <a name = "fields"></a>
    <strong>fields&nbsp;(spec, f)</strong>
    </dt>
    <dd>
    given a pattern and a file object, return an iterator over the results 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>f</em></code>:  a file &ndash; use standard input if not specified.</li>
    </ul>




</dd>
    <dt>
    <a name = "pattern"></a>
    <strong>pattern&nbsp;(spec, fun)</strong>
    </dt>
    <dd>
    register a match which will be used in the read function. 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>spec</em></code>:  a SIP pattern</li>
       <li><code><em>fun</em></code>:  a function to be called with the results of the match</li>
    </ul>




    <h3>see also:</h3>
    <ul>
         <a href="../modules/pl.sip.html#read">read</a>
    </ul>
</dd>
    <dt>
    <a name = "read"></a>
    <strong>read&nbsp;(f)</strong>
    </dt>
    <dd>
    enter a loop which applies all registered matches to the input file. 

    <h3>Parameters:</h3>
    <ul>
       <li><code><em>f</em></code>:  a file object; if nil, then io.stdin is assumed.</li>
    </ul>




</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.2</a></i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
